What is busboy?
The busboy npm package is a Node.js module for parsing incoming HTML form data, particularly file uploads. It is a stream-based parser that can handle multipart/form-data, which is primarily used for uploading files via HTTP.
What are busboy's main functionalities?
File Upload Parsing
This code sample demonstrates how to use busboy to parse file uploads from an HTML form. When a file is received, it logs the file details and the amount of data received.
const Busboy = require('busboy');
const http = require('http');
http.createServer((req, res) => {
if (req.method === 'POST') {
const busboy = new Busboy({ headers: req.headers });
busboy.on('file', (fieldname, file, filename, encoding, mimetype) => {
console.log(`File [${fieldname}]: filename: ${filename}, encoding: ${encoding}, mimetype: ${mimetype}`);
file.on('data', (data) => {
console.log(`File [${fieldname}] got ${data.length} bytes`);
}).on('end', () => {
console.log(`File [${fieldname}] Finished`);
});
});
busboy.on('finish', () => {
console.log('Done parsing form!');
res.writeHead(303, { Connection: 'close', Location: '/' });
res.end();
});
req.pipe(busboy);
} else {
res.writeHead(404);
res.end();
}
}).listen(8000, () => {
console.log('Server listening on port 8000');
});
Field Parsing
This code sample shows how to use busboy to parse non-file fields from an HTML form. It logs the name and value of each field received.
const Busboy = require('busboy');
const http = require('http');
http.createServer((req, res) => {
if (req.method === 'POST') {
const busboy = new Busboy({ headers: req.headers });
busboy.on('field', (fieldname, val, fieldnameTruncated, valTruncated, encoding, mimetype) => {
console.log(`Field [${fieldname}]: value: ${val}`);
});
busboy.on('finish', () => {
res.end('Done parsing form!');
});
req.pipe(busboy);
} else {
res.writeHead(404);
res.end();
}
}).listen(8000, () => {
console.log('Server listening on port 8000');
});
Other packages similar to busboy
formidable
Formidable is an npm package similar to busboy that is used for parsing form data, especially file uploads. It is also stream-based and can handle multipart/form-data. Compared to busboy, Formidable provides a higher-level abstraction and can also handle file uploads to disk, but it might be less efficient for large file uploads due to its buffering approach.
multiparty
Multiparty is another npm package for parsing multipart/form-data. Like busboy, it is stream-based and suitable for handling large file uploads. However, multiparty differs in its API and the way it handles parts of the form data, which may make it more suitable for certain use cases.
multer
Multer is a middleware for Express.js that handles multipart/form-data, which is primarily used for uploading files. It is built on top of busboy for maximum efficiency. Unlike busboy, which is a general-purpose stream parser, multer provides a set of convenient features specifically designed for Express applications.
Description
A node.js module for parsing incoming HTML form data.
Changes (breaking or otherwise) in v1.0.0 can be found here.
Requirements
Install
npm install busboy
Examples
- Parsing (multipart) with default options:
const http = require('http');
const busboy = require('busboy');
http.createServer((req, res) => {
if (req.method === 'POST') {
console.log('POST request');
const bb = busboy({ headers: req.headers });
bb.on('file', (name, file, info) => {
const { filename, encoding, mimeType } = info;
console.log(
`File [${name}]: filename: %j, encoding: %j, mimeType: %j`,
filename,
encoding,
mimeType
);
file.on('data', (data) => {
console.log(`File [${name}] got ${data.length} bytes`);
}).on('close', () => {
console.log(`File [${name}] done`);
});
});
bb.on('field', (name, val, info) => {
console.log(`Field [${name}]: value: %j`, val);
});
bb.on('close', () => {
console.log('Done parsing form!');
res.writeHead(303, { Connection: 'close', Location: '/' });
res.end();
});
req.pipe(bb);
} else if (req.method === 'GET') {
res.writeHead(200, { Connection: 'close' });
res.end(`
<html>
<head></head>
<body>
<form method="POST" enctype="multipart/form-data">
<input type="file" name="filefield"><br />
<input type="text" name="textfield"><br />
<input type="submit">
</form>
</body>
</html>
`);
}
}).listen(8000, () => {
console.log('Listening for requests');
});
- Save all incoming files to disk:
const { randomFillSync } = require('crypto');
const fs = require('fs');
const http = require('http');
const os = require('os');
const path = require('path');
const busboy = require('busboy');
const random = (() => {
const buf = Buffer.alloc(16);
return () => randomFillSync(buf).toString('hex');
})();
http.createServer((req, res) => {
if (req.method === 'POST') {
const bb = busboy({ headers: req.headers });
bb.on('file', (name, file, info) => {
const saveTo = path.join(os.tmpdir(), `busboy-upload-${random()}`);
file.pipe(fs.createWriteStream(saveTo));
});
bb.on('close', () => {
res.writeHead(200, { 'Connection': 'close' });
res.end(`That's all folks!`);
});
req.pipe(bb);
return;
}
res.writeHead(404);
res.end();
}).listen(8000, () => {
console.log('Listening for requests');
});
API
Exports
busboy
exports a single function:
( function )(< object >config) - Creates and returns a new Writable form parser stream.
-
Valid config
properties:
-
headers - object - These are the HTTP headers of the incoming request, which are used by individual parsers.
-
highWaterMark - integer - highWaterMark to use for the parser stream. Default: node's stream.Writable default.
-
fileHwm - integer - highWaterMark to use for individual file streams. Default: node's stream.Readable default.
-
defCharset - string - Default character set to use when one isn't defined. Default: 'utf8'
.
-
defParamCharset - string - For multipart forms, the default character set to use for values of part header parameters (e.g. filename) that are not extended parameters (that contain an explicit charset). Default: 'latin1'
.
-
preservePath - boolean - If paths in filenames from file parts in a 'multipart/form-data'
request shall be preserved. Default: false
.
-
limits - object - Various limits on incoming data. Valid properties are:
-
fieldNameSize - integer - Max field name size (in bytes). Default: 100
.
-
fieldSize - integer - Max field value size (in bytes). Default: 1048576
(1MB).
-
fields - integer - Max number of non-file fields. Default: Infinity
.
-
fileSize - integer - For multipart forms, the max file size (in bytes). Default: Infinity
.
-
files - integer - For multipart forms, the max number of file fields. Default: Infinity
.
-
parts - integer - For multipart forms, the max number of parts (fields + files). Default: Infinity
.
-
headerPairs - integer - For multipart forms, the max number of header key-value pairs to parse. Default: 2000
(same as node's http module).
This function can throw exceptions if there is something wrong with the values in config
. For example, if the Content-Type in headers
is missing entirely, is not a supported type, or is missing the boundary for 'multipart/form-data'
requests.
(Special) Parser stream events
-
file(< string >name, < Readable >stream, < object >info) - Emitted for each new file found. name
contains the form field name. stream
is a Readable stream containing the file's data. No transformations/conversions (e.g. base64 to raw binary) are done on the file's data. info
contains the following properties:
-
filename
- string - If supplied, this contains the file's filename. WARNING: You should almost never use this value as-is (especially if you are using preservePath: true
in your config
) as it could contain malicious input. You are better off generating your own (safe) filenames, or at the very least using a hash of the filename.
-
encoding
- string - The file's 'Content-Transfer-Encoding'
value.
-
mimeType
- string - The file's 'Content-Type'
value.
Note: If you listen for this event, you should always consume the stream
whether you care about its contents or not (you can simply do stream.resume();
if you want to discard/skip the contents), otherwise the 'finish'
/'close'
event will never fire on the busboy parser stream.
However, if you aren't accepting files, you can either simply not listen for the 'file'
event at all or set limits.files
to 0
, and any/all files will be automatically skipped (these skipped files will still count towards any configured limits.files
and limits.parts
limits though).
Note: If a configured limits.fileSize
limit was reached for a file, stream
will both have a boolean property truncated
set to true
(best checked at the end of the stream) and emit a 'limit'
event to notify you when this happens.
-
field(< string >name, < string >value, < object >info) - Emitted for each new non-file field found. name
contains the form field name. value
contains the string value of the field. info
contains the following properties:
-
nameTruncated
- boolean - Whether name
was truncated or not (due to a configured limits.fieldNameSize
limit)
-
valueTruncated
- boolean - Whether value
was truncated or not (due to a configured limits.fieldSize
limit)
-
encoding
- string - The field's 'Content-Transfer-Encoding'
value.
-
mimeType
- string - The field's 'Content-Type'
value.
-
partsLimit() - Emitted when the configured limits.parts
limit has been reached. No more 'file'
or 'field'
events will be emitted.
-
filesLimit() - Emitted when the configured limits.files
limit has been reached. No more 'file'
events will be emitted.
-
fieldsLimit() - Emitted when the configured limits.fields
limit has been reached. No more 'field'
events will be emitted.